home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Libraries / ToolLib 1.0 / ToolLib.h next >
Encoding:
C/C++ Source or Header  |  1990-09-14  |  7.2 KB  |  193 lines  |  [TEXT/MPS ]
  1. /*
  2.  *
  3.  *  ToolLib.h - Interface file for functions contained in
  4.  *        ToolLib library.  These functions can be used by
  5.  *        programs that are to be operated as tools under the
  6.  *        APW shell on the Apple IIgs.
  7.  *
  8.  *    Copyright Apple Computer, Inc. 1989
  9.  *    All rights reserved
  10.  *
  11.  *    Author: Greg Branche
  12.  *
  13.  */
  14.  
  15. #ifndef    __ToolLib__
  16. #define __ToolLib__
  17.  
  18. /************************************************************
  19.  
  20.     <<< CursorCtl - Cursor Control Routines >>>
  21.  
  22.     This file contains:
  23.     
  24.     InitCursorCtl(delaycount) - Init CursorCtl to set the spin delay
  25.     RotateCursor(counter) - Sequence through cursor frames for counter mod delay
  26.     SpinCursor(increment) - Sequence mod delay incrementing internal counter
  27.     Hide_Cursor() - Hide the current cursor
  28.     Show_Cursor() - Show the cursor
  29.  
  30. ************************************************************/
  31.  
  32. extern pascal void InitCursorCtl(/* delaycount */);/*
  33. unsigned long    delaycount;
  34.  
  35.     Initialize the CursorCtl unit.  This should be called once prior to calling
  36.     any of the other CursorCtl routines.  If delaycount = 0, then the default delay
  37.     value of 32 will be used.  Ensure that the value being passed as delaycount is
  38.     32-bits in size (long)
  39. */
  40.  
  41. extern pascal void Show_Cursor();/*
  42.  
  43.     This function removes the default inverse space cursor from the screen and replaces it
  44.     with the first frame of the animated cursor.  It then outputs a backspace so that any
  45.     subsequent characters will automatically overwrite the cursor character.
  46. */
  47.  
  48. extern pascal void RotateCursor(/* counter */);/*
  49. unsigned long    counter;
  50.  
  51.     RotateCursor is called to rotate the "I am active" "spinning wheel" cursor.  The next cursor
  52.     ("frame") is used when (counter MOD delaycount) (as specified in the InitCursorCtl call) = 0
  53.     (counter is some kind of incrementing or decrementing index maintained by the caller).  A 
  54.     positive counter sequences forward through the cursors (e.g., it rotates the cursor
  55.     "clockwise"), and a negative cursor sequences through the cursors backwards (e.g., it
  56.     rotates the cursor counterclockwise).
  57. */
  58.  
  59. extern pascal void SpinCursor(/* increment */);/*
  60. unsigned short    increment;
  61.  
  62.     SpinCursor is similar in function to RotateCursor, except that instead of passing a counter,
  63.     an increment is passed and added to a counter maintained here.  SpinCursor is provided for
  64.     those users who do not happen to have a convenient counter handy but still want to use the
  65.     spinning cursor.  A positive increment sequences forward through the cursors (rotating the
  66.     cursor clockwise), and a negative increment sequences backward through the cursors (rotating
  67.     the cursor counterclockwise).  A zero value for the increment resets the counter to zero.
  68.     Note, it is the increment, and not the value of the counter that determines the sequencing
  69.     direction of the cursor (and hence the spin direction of the cursor).
  70. */
  71.  
  72. extern pascal void Hide_Cursor();/*
  73.  
  74.     Hides the current character of the spinning cursor.  Use this routine when you wish to
  75.     revert to the standard inverse space cursor.
  76. */
  77.  
  78. /************************************************************
  79.  
  80.     ErrMgr.h - //GS equivalent of the MPW Error Manager
  81.  
  82. ************************************************************/
  83.  
  84. extern void InitErrMgr(/* toolErrFilename, sysErrFilename, showToolErrNbrs */);
  85. /*    char    *toolErrFilename;
  86.     char    *sysErrFilename;
  87.     boolean    showToolErrNbrs;
  88.  
  89.     Initializes the error manager.  If toolErrFilename is not null, this will open the resource fork
  90.     of that file to allow access to tool-specific error messages.  If sysErrFilename is not null,
  91.     this will open the resource fork of that file instead of the standard APW error message file.
  92.     If showToolErrNbrs is TRUE, then any call to GetSysErrText will show the decimal and hexadecimal
  93.     error number in parentheses after the text of the error message.  If this is false, all that
  94.     GetSysErrText will provide is the text of the message.
  95.     
  96.     To use the error manager, your tool must start up the Resource Manager prior to calling
  97.     InitErrMgr.  This function will NOT do it for you.
  98. */
  99.  
  100. extern void CloseErrMgr();
  101. /*
  102.     This simply closes any resources files opened by InitErrMgr.  It is not absolutely required that
  103.     you call this function prior to exiting your tool, but it is available.  If it is not called, the
  104.     Resource Manager will automatically close any files opened.  You must shutdown the Resource
  105.     Manager yourself.
  106. */
  107.  
  108. extern char *GetSysErrText(/* errNbr,errMsg */);
  109. /*    unsigned    errNbr;
  110.     StringPtr    errMsg;
  111.  
  112.     GetSysErrText performs a resource lookup for the supplied errNbr.  It does this by calculating
  113.     which resource number to use from the system resource file or the tool-specific error file.  
  114.  
  115.     The function places the error message text in the buffer pointed to by errMsg, and also returns
  116.     a pointer to a standard C string representing the error message associated with the given error
  117.     number.  If there is message text available for the given error number, the string will have
  118.     the following format:
  119.  
  120.         ### {tool name}: {message text}
  121.     
  122.     If no specific message is available, the string will have the following format:
  123.  
  124.         ### {tool name}: Error {decimal error number} ($xxxx)
  125.  
  126.     where $xxxx is the hexadecimal error code.
  127. */
  128.  
  129. /************************************************************
  130.  
  131.     gsString.h - header file for GS/OS string support functions
  132.  
  133. ************************************************************/
  134.  
  135. #ifdef    __GSOS__
  136.  
  137. extern    GSString255    *c2gsstr(/* str, pathGS */);
  138. /*    char        *str;
  139.     GSString255    *pathGS;
  140.     
  141.     This function accepts a null terminated C string and copies it to a
  142.     GS/OS-style string (length word followed by the characters of the string).
  143.     On return, the function returns the pointer to the pathname structure
  144. */
  145.  
  146. extern    char *gs2cstr(/* pathGS, str */);
  147. /*    GSString255    pathGS;
  148.     char        *str;
  149.     
  150.     This function converts a GS/OS-style string (word length followed by the
  151.     characters of the string) to a normal, null terminated C string.  On exit
  152.     it returns a pointer to the string (which is the same as that specified
  153.     on entry).
  154. */
  155.  
  156. extern void colonize(/* fileName */);
  157. /*    char    *fileName;
  158.  
  159.     normalizes a filename string so that it contains only colons as pathname
  160.     separators.  If there are no separators in the filename, the name is left
  161.     unchanged.  If the filename contains no slashes, the filename is left
  162.     unchanged.
  163. */
  164. #endif
  165.  
  166. /************************************************************
  167.  
  168.     pause.h - header file for APW-compatible pause function
  169.  
  170. ************************************************************/
  171.  
  172. extern int pause();
  173. /*
  174.     This function should be called periodically by an APW tool to check for
  175.     a pending keypress and/or command-. (abort signal).  If the command-.
  176.     keypress is pending, the function will return a non-zero value
  177.     (signifying TRUE).  If any other keypress is pending, the function
  178.     will display an hourglass character on the screen and pause until
  179.     another key is pressed.
  180.     
  181.     The value returned is either non-zero (TRUE), indicating that command-.
  182.     has been pressed and the tool should abort, or 0 (false), indicating
  183.     that processing should proceed.
  184. */
  185.  
  186. extern int wait();
  187. /*
  188.     This function operates similarly to the pause() function, except that
  189.     it forces a keypress prior to returning to the caller.  That is, it
  190.     waits in a loop until a keypress occurs.  The values returned are the 
  191.     same as described for the pause() function.
  192. */
  193. #endif